AuthZenService

[Experimental] Search for subjects with access to a resource

[Experimental] The SubjectSearch API returns all subjects that have a specific action (relation) on a given resource. This is useful for answering questions like “Who can read this document?” or “Who can administer this folder?”

Results can be filtered by subject type and support pagination for large result sets.

Examples

Find all users who can read a document

{
  "resource": {"type": "document", "id": "roadmap"},
  "action": {"name": "can_read"},
  "subject": {"type": "user"}
}

Response:

{
  "results": [
    {"type": "user", "id": "anne"},
    {"type": "user", "id": "bob"},
    {"type": "user", "id": "charlie"}
  ],
  "page": {"count": 3}
}

Paginated search with limit

{
  "resource": {"type": "folder", "id": "engineering"},
  "action": {"name": "can_view"},
  "subject": {"type": "user"},
  "page": {"limit": 10}
}

Continue from previous page

{
  "resource": {"type": "folder", "id": "engineering"},
  "action": {"name": "can_view"},
  "subject": {"type": "user"},
  "page": {"token": "eyJsYXN0X2lkIjoiMTAwIn0=", "limit": 10}
}

POST

stores

{store_id}

access

subject

curl

# HTTP only: no named client or generated low-level operation in the audited SDK versions.
# Set FGA_API_URL to the URL of your OpenFGA server.
# Set FGA_STORE_ID to your store ID.
# These examples use a server with authentication disabled.
# For authenticated servers, see /docs/getting-started/setup-sdk-client.

curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/access/v1/search/subject" \
  -H "content-type: application/json" \
  -d '{
  "subject": {
    "type": "user"
  },
  "action": {
    "name": "reader"
  },
  "resource": {
    "type": "document",
    "id": "budget"
  }
}'

{
  "page": {
    "count": 123,
    "next_token": "<string>",
    "total": 123
  },
  "results": [
    {
      "id": "anne",
      "type": "user",
      "properties": {}
    }
  ]
}

{
  "code": "validation_error",
  "message": "Generic validation error"
}

{
  "code": "unauthenticated",
  "message": "unauthenticated"
}

{
  "code": "forbidden",
  "message": "the principal is not authorized to perform the action"
}

{
  "code": "undefined_endpoint",
  "message": "Endpoint not enabled"
}

{
  "code": "10",
  "message": "transaction conflict"
}

{
  "code": "throttled_timeout_error",
  "message": "timeout due to throttling on complex request"
}

{
  "code": "internal_error",
  "message": "Internal Server Error"
}

Path Parameters

store_id

string

required

Body

application/json

action

object

required

Show child attributes

resource

object

required

Show child attributes

subject

SubjectFilter is used for search operations where only type is required · object

required

REQUIRED by AuthZEN Subject Search. Subject id may be provided but is ignored.

Show child attributes

context

object

page

Pagination request parameters for search operations · object

Show child attributes

Response

A successful response.

page

Optional per AuthZEN spec - omit if pagination not supported · object

Show child attributes

results

object[]

Show child attributes

Last modified on September 28, 2026

⌘I

curl

# HTTP only: no named client or generated low-level operation in the audited SDK versions.
# Set FGA_API_URL to the URL of your OpenFGA server.
# Set FGA_STORE_ID to your store ID.
# These examples use a server with authentication disabled.
# For authenticated servers, see /docs/getting-started/setup-sdk-client.

curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/access/v1/search/subject" \
  -H "content-type: application/json" \
  -d '{
  "subject": {
    "type": "user"
  },
  "action": {
    "name": "reader"
  },
  "resource": {
    "type": "document",
    "id": "budget"
  }
}'

{
  "page": {
    "count": 123,
    "next_token": "<string>",
    "total": 123
  },
  "results": [
    {
      "id": "anne",
      "type": "user",
      "properties": {}
    }
  ]
}

{
  "code": "validation_error",
  "message": "Generic validation error"
}

{
  "code": "unauthenticated",
  "message": "unauthenticated"
}

{
  "code": "forbidden",
  "message": "the principal is not authorized to perform the action"
}

{
  "code": "undefined_endpoint",
  "message": "Endpoint not enabled"
}

{
  "code": "10",
  "message": "transaction conflict"
}

{
  "code": "throttled_timeout_error",
  "message": "timeout due to throttling on complex request"
}

{
  "code": "internal_error",
  "message": "Internal Server Error"
}

Stores

Authorization Models

Relationship Tuples

Relationship Queries

Assertions

AuthZenService

[Experimental] Search for subjects with access to a resource

Examples

Find all users who can read a document

Paginated search with limit

Continue from previous page

Path Parameters

Body

Response